What is CMOD?

CMOD is the name of a simplified mechanism for writing extensions to the Pike programming language. CMOD files consist of C language code plus simplified function definition elements that handle many of the most tedious tasks associated with module development. A CMOD file is pre-processed by the CMOD precompiler resulting in a standard C file that is then compiled normally.

Tasks the CMOD compiler takes care of:

• Module initialization and shutdown
• Class definition
• Storage allocation for objects (including modules)
• Function definition and registration
• Variable definition and storage
• Function argument checking and passing
• Return value handling
• Polymorphic function overloading (function variants based on function type signature)

• Parenthesis must match, even within #if 0
• Not all Pike types are supported yet.
• No support for functions that take a variable number of arguments yet.
• RETURN; (void) doesn't work yet
• need a RETURN_NULL; or something.. RETURN 0; might work but may be confusing as RETURN x; will not work if x is zero.

In short, for most module applications, using CMOD can save you a large amount of time and effort, particularly in the area of avoiding bugs. Function bodies are written using standard C, so programming skills will transfer directly.

Sample module

A sample module that can be used as a starting point for further module development can be found at http://buoy.riverweb.com:8080/viewrep/cvs/pike_modules/SampleModule

This sample module represents a minimal CMOD module with a Pike module over-wrapper. The over-wrapper in this case is non-functional, and is included to show the necessary constants for providing module repository functionality.

Elements of a CMOD file

The following represents the basic structure of a CMOD file. We'll cover each element in turn afterward.

// PIKE INCLUDES MUST BE PRESENT FOR COMPILATION.
PIKECLASS fnord
    attributes;
{
  INHERIT bar
    attributes;
  CVAR int foo;
  PIKEVAR mapping m
    attributes;
  DECLARE_STORAGE; // optional
  PIKEFUN int function_name (int x, CTYPE char * foo)
   attribute;
   attribute value;
  {
     C code using 'x' and 'foo'.
      RETURN x;
  }
    INIT
   {
     // Object initialization code.
   }
   EXIT
   {
     // Object cleanup code.
   }
    GC_RECURSE
   {
     // Code to run under the gc recurse pass.
   }
   GC_CHECK
   {
     // Code to run under the gc check pass.
   }
   EXTRA
   {
     // Code for adding extra constants etc.
   }
    OPTIMIZE
   {
     // Code for optimizing calls that clone the class.
     // The node for the call is available in the variable n.
   }
 }

PIKECLASS is used to define the code for a given class in Pike. These code blocks may be nested in order to provide sub-classes, and multiple PIKECLASS blocks may appear sequentially within a given CMOD file. Strictly speaking, the PIKECLASS definition is optional, in as far as without one, there will be no class, and any variables and functions will appear directly within the resulting module. Note that if you are combining multiple CMOD files into one module, you may only use this technique within one of them, otherwise you will get compiler conflicts.

PIKECLASS/PIKEFUN Attributes

INHERIT

CVAR

PIKEVAR

PIKEFUN

INIT

EXIT

EXTRA

GC_CHECK

GC_RECURSE

OPTIMIZE

Multiple CMOD files in a single module

At a certain point, a module cannot be reasonably managed as a single source file. Typically, a module will be split into multiple classes, and it is often desirable to have each class be contained in a separate file. The Pike module build system will happily compile multiple CMOD files and link them into a single module shared object. However, a few steps must be taken in order for the resulting object to be functional.

Powered by PikeWiki2